home *** CD-ROM | disk | FTP | other *** search
/ Sound Fx / Sound Fx.iso / Software / UNZIPED / DWSTK / DWS.BI < prev    next >
Text File  |  1996-10-09  |  11KB  |  278 lines
  1. '******************************************************************************
  2. 'File:      dws.bi
  3. 'Version:   2.22
  4. 'Tab stops: every 2 columns
  5. 'Project:   DiamondWare's Sound ToolKit
  6. 'Copyright: 1994-1995 DiamondWare, Ltd.  All rights reserved.
  7. 'Written:   by Erik Lorenzen, Keith Weiner, and Don Lemons
  8. 'Purpose:   Contains declarations for the DW Sound ToolKit
  9. 'History:   94/08/24 DL Started translation
  10. '           94/08/30 KW Modified
  11. '           94/11/12 DL Re-Translated
  12. '           94/11/26 EL Edited for clarity and funtionality
  13. '           94/11/27 EL Finalized for 1.0
  14. '           95/03/19 EL Finalized for 1.01, Added new CONST dwsBUSY
  15. '           95/04/06 EL Finalized for 1.02, Added new define dwsIRQDISABLED
  16. '           95/06/06 EL Finalized for 1.03, no changes
  17. '           95/07/23 EL Finalized for 1.04, no changes
  18. '           95/08/01 EL Finalized for 2.00, no changes
  19. '           95/08/29 EL Finalized for 2.10, no changes
  20. '           95/10/18 EL Finalized for 2.20, no changes
  21. '           95/12/07 EL Finalized for 2.21, no changes
  22. '           96/10/11 EL Finalized for 2.22, no changes
  23. '
  24. '******************************************************************************
  25.  
  26.  
  27.  
  28. '******************************************************************************
  29. ' The following is the complete list of possible values for dwsErrNo.
  30. ' dwsErrNo may be set by any dws function.  Check its value whenever
  31. ' the return value of a dws function is 0 (error).
  32.  
  33. CONST dwsEZERO                                                    =  0
  34.  
  35. ' The following 3 errors may be triggered by any dws function
  36. CONST dwsNOTINITTED                                         =  1
  37. CONST dwsALREADYINITTED                                 =  2
  38. CONST dwsNOTSUPPORTED                                     =  3
  39.  
  40. 'The following 4 errors may be triggered by dwsDetectHardWare
  41. CONST dwsDetectHardwareUNSTABLESYSTEM     =  4
  42. CONST dwsDetectHardwareBADBASEPORT            =  5
  43. CONST dwsDetectHardwareBADDMA                     =  6
  44. CONST dwsDetectHardwareBADIRQ                     =  7
  45.  
  46. 'The following error may be triggered by dwsKill
  47. CONST dwsKillCANTUNHOOKISR                            =  8
  48.  
  49. 'The following error may be triggered by any dwsX (mixer) function
  50. CONST dwsXBADINPUT                                            =  9
  51.  
  52. 'The following 3 errors may be triggered by any dwsD (dig) function
  53. CONST dwsDNOTADWD                                             =  10
  54. CONST dwsDNOTSUPPORTEDVER                             =  11
  55. CONST dwsDINTERNALERROR                                 =  12
  56.  
  57. 'The following error may be triggered by dwsDPlay
  58. CONST dwsDPlayNOSPACEFORSOUND                     =  13
  59.  
  60. 'The following 2 errors may be triggered by dwsDSetRate
  61. CONST dwsDSetRateFREQTOLOW                            =  14
  62. CONST dwsDSetRateFREQTOHIGH                         =  15
  63.  
  64. 'The following 3 errors may be triggered by dwsMPlay
  65. CONST dwsMPlayNOTADWM                                     =  16
  66. CONST dwsMPlayNOTSUPPORTEDVER                     =  17
  67. CONST dwsMPlayINTERNALERROR                         =  18
  68.  
  69. 'The following error may be triggered by any dws_ function
  70. '(except dws_ErrNo and dws_Init) if called from an Interrupt
  71. 'Service Routine (ISR).  If you're not sure whether this applies
  72. 'to you: it probably doesn't.
  73. CONST dwsBUSY                                                     =  19
  74.  
  75. 'The following error may be triggered by dws_Init, dws_Kill,
  76. 'and dws_DetectHardware.  It will only occur if interrupts are
  77. 'disabled.  Interrupts must be enabled when calling.  If you're
  78. 'not sure whether this applies to you: it probably doesn't.
  79. CONST dwsIRQDISABLED                                        =  20
  80.  
  81.  
  82. '------------------------------------------------------------------------------
  83.  
  84.  
  85. 'The follwing section defines bitfields which are used by various
  86. 'dws functions.  Each bit in a bitfield, by definition, may be
  87. 'set/reset independantly of all other bits.
  88.  
  89. 'The following 2 consts indicate the capabilities of the user's hardware
  90. CONST dwscapabilityFM                                     =  1
  91. CONST dwscapabilityDIG                                    =  2
  92.  
  93. 'The following 2 consts indicate the status of specified digital sounds
  94. CONST dwsDSOUNDSTATUSPLAYING                        =  1
  95. CONST dwsDSOUNDSTATUSSEQUENCED                    =  2
  96.  
  97. 'The following 2 consts indicate the status of music playback
  98. CONST dwsMSONGSTATUSPLAYING                         =  1
  99. CONST dwsMSONGSTATUSPAUSED                            =  2
  100. '******************************************************************************
  101.  
  102.  
  103.  
  104. 'The following section TYPEs the structs used by the STK.  In each
  105. 'case, the user must create an instance of the struct prior to making
  106. 'a call to an STK function which takes a pointer to it.  The STK does
  107. 'not keep a pointer to any of these structs internally; after the call
  108. 'returns, you may deallocate it, if you wish.
  109.  
  110.  
  111. 'NB: The STK _does_ keep pointers to songs and digitized sound buffers!
  112.  
  113.  
  114. 'dws_DetectHardWare can be told _not_ to autodetect particular values
  115. 'about the installed hardware.  This is useful if detecting DMA channel,
  116. 'for example, consistently causes a machine lockup.  To override the
  117. 'autodetect for a setting, set the corresponding field in this struct
  118. 'to the correct value.  Otherwise, set the field to ffff hex.  Since
  119. 'the autodetect is reliable, this is the recommended course of action,
  120. 'except in cases of known problems.
  121. TYPE dwsDETECTOVERRIDES
  122.     baseport     AS INTEGER          'base address of sound card (often 220 hex)
  123.  
  124.     digdma         AS INTEGER          'DMA channel
  125.     digirq         AS INTEGER          'IRQ level
  126.  
  127.     reserved     AS STRING * 10  'reserved
  128.  
  129. END TYPE
  130.  
  131.  
  132. 'A pointer to this struct is passed to dwsDetectHardWare, which fills
  133. 'it in.  It is then passed unmodified to dwsInit.  If you plan on
  134. 'writing this struct out to a file, it's important that you write
  135. 'the entire contents.  There is information (for internal STK use only)
  136. 'in the reserved[] field!
  137. TYPE dwsDETECTRESULTS
  138.     baseport     AS INTEGER          'base address of sound card (often 220 hex)
  139.     capability AS INTEGER          'see CONSTs, above
  140.  
  141.     'The following 3 fields are only valid if FM music is supported
  142.     mustyp         AS INTEGER          '0=none, 1=OPL2
  143.     musnchan     AS INTEGER          '1=mono
  144.     musnvoice  AS INTEGER          'number of voices supported by hardware (11 for FM)
  145.  
  146.     'The following 2 fields are only valid if digitized sound is supported
  147.     dignbits     AS INTEGER          '0=none, 8=8 bit
  148.     dignchan     AS INTEGER          '1=mono
  149.  
  150.     digdma         AS INTEGER          'DMA channel
  151.     digirq         AS INTEGER          'IRQ level
  152.  
  153.     mixtyp         AS INTEGER          '1=software, 2+ is hardware
  154.  
  155.     reserved     AS STRING * 44  'there are important values in here...
  156.  
  157. END TYPE
  158.  
  159.  
  160. 'A pointer to this struct is passed as a parameter to dws_Init.  This
  161. 'allows the user to tell the STK to use less than the full capabilities
  162. 'of the installed sound hardware, and/or the user's sound board
  163. 'may not support every feature of the STK.
  164. TYPE dwsIDEAL
  165.     musictyp     AS INTEGER          '0=No Music, 1=OPL2
  166.  
  167.     digtyp         AS INTEGER          '0=No Dig, 8=8bit
  168.     digrate      AS INTEGER          'sampling rate, in Hz
  169.     dignvoices AS INTEGER          'number of voices (up to 16)
  170.     dignchan     AS INTEGER          '1=mono
  171.  
  172.     reserved     AS STRING * 6
  173.  
  174. END TYPE
  175.  
  176.  
  177. 'A pointer to this struct is passed to dwsDPlay.
  178. 'Note that the soundnum field is filled in by dws_DPlay as a return value.
  179. TYPE dwsDPLAY
  180.     snd              AS LONG                 'pointer to buffer which holds a .DWD file
  181.     count          AS INTEGER          'number of times to play, or 0=infinite loop
  182.     priority     AS INTEGER          'higher numbers mean higher priority
  183.     presnd         AS INTEGER          'soundnum to sequence sound _after_
  184.     soundnum     AS INTEGER          'dws_DPlay returns a snd number from 10-65535
  185.  
  186.     reserved     AS STRING * 20
  187.  
  188. END TYPE
  189.  
  190.  
  191. 'A pointer to this struct is passed to dwsMPlay.
  192. TYPE dwsMPLAY
  193.     track          AS LONG                 'pointer to buffer which holds a .DWM file
  194.     count          AS INTEGER          'number of times to play, or 0=infinite loop
  195.  
  196.     reserved     AS STRING * 10
  197.  
  198. END TYPE
  199. '******************************************************************************
  200.  
  201.  
  202. '******************************************************************************
  203.  
  204. 'This function is callable at any time.  It returns the number of the
  205. 'last error which occured.
  206. DECLARE FUNCTION dwsErrNo%                     ALIAS "DWS_ERRNO"                    ()
  207. '------------------------------------------------------------------------------
  208.  
  209.  
  210. 'This subroutine is called at the end of the timer ISR (interrupt service
  211. 'routine).  If you're using the optional DWT (DW Timer), this happens
  212. 'automagically.  If you wrote your own timer handler routine, you must
  213. 'call this function regularly.
  214. DECLARE SUB          dwsUpdate                     ALIAS "DWS_UPDATE"                 ()
  215. '------------------------------------------------------------------------------
  216.  
  217.  
  218. 'The following functions have boolean return values.  A return of 0 (false)
  219. 'indicates an error.  If this occurs, check dwsErrNo for more info.
  220. DECLARE FUNCTION dwsDetectHardWare%  ALIAS "DWS_DETECTHARDWARE" (SEG dov AS dwsDetectOverrides, SEG dres AS dwsDetectResults)
  221.  
  222. DECLARE FUNCTION dwsInit%                      ALIAS "DWS_INIT"                     (SEG dres AS dwsDetectResults, SEG idl AS dwsIdeal)
  223.  
  224.  
  225. 'If the program has called dws_Init, it _MUST_ call dws_Kill before it
  226. 'terminates.
  227. '
  228. 'NB: Trap critical errors.  Don't let DOS put up the
  229. '    "Abort, Retry, Fail?" text.  ('sides, it'll destroy your pretty gfx)
  230. DECLARE FUNCTION dwsKill%                      ALIAS "DWS_KILL"                     ()
  231.  
  232.  
  233. 'The following 3 functions comprise the mixer section of the STK.  A
  234. 'value of 0 turns a channel off; a value of 255 is the loudest.
  235. DECLARE FUNCTION dwsXMaster%                 ALIAS "DWS_XMASTER"                (BYVAL volume%)
  236.  
  237. DECLARE FUNCTION dwsXMusic%                  ALIAS "DWS_XMUSIC"                 (BYVAL volume%)
  238.  
  239. DECLARE FUNCTION dwsXDig%                      ALIAS "DWS_XDIG"                     (BYVAL volume%)
  240.  
  241.  
  242. 'The following 10 functions comprise the digitized sound functions of
  243. 'the STK.  See the documentation for complete details.
  244. DECLARE FUNCTION dwsDPlay%                     ALIAS "DWS_DPLAY"                    (SEG dply AS dwsDPlay)
  245.  
  246. DECLARE FUNCTION dwsDSoundStatus%      ALIAS "DWS_DSOUNDSTATUS"     (BYVAL soundnumber%, SEG result%)
  247.  
  248. DECLARE FUNCTION dwsDSetRate%              ALIAS "DWS_DSETRATE"             (BYVAL frequency%)
  249.  
  250. DECLARE FUNCTION dwsDGetRate%              ALIAS "DWS_DGETRATE"             (SEG result%)
  251.  
  252. 'This function is callable at any time.
  253. DECLARE FUNCTION dwsDGetRateFromDWD% ALIAS "DWS_DGETRATEFROMDWD"(BYVAL pointer&, SEG result%)
  254.  
  255. DECLARE FUNCTION dwsDDiscard%              ALIAS "DWS_DDISCARD"             (BYVAL soundnum%)
  256.  
  257. DECLARE FUNCTION dwsDDiscardAO%          ALIAS "DWS_DDISCARDAO"         (BYVAL pointer&)
  258.  
  259. DECLARE FUNCTION dwsDClear%                  ALIAS "DWS_DCLEAR"                 () 'Affects all sounds
  260.  
  261. DECLARE FUNCTION dwsDPause%                  ALIAS "DWS_DPAUSE"                 () 'Affects all sounds
  262.  
  263. DECLARE FUNCTION dwsDUnPause%              ALIAS "DWS_DUNPAUSE"             () 'Affects all sounds
  264.  
  265.  
  266. 'The following 5 functions comprise the music functions of the STK.
  267. 'See the documentation for complete details.
  268. DECLARE FUNCTION dwsMPlay%                     ALIAS "DWS_MPLAY"                    (SEG mply AS dwsMPlay)
  269.  
  270. DECLARE FUNCTION dwsMSongStatus%         ALIAS "DWS_MSONGSTATUS"        (SEG result%)
  271.  
  272. DECLARE FUNCTION dwsMClear%                  ALIAS "DWS_MCLEAR"                 ()
  273.  
  274. DECLARE FUNCTION dwsMPause%                  ALIAS "DWS_MPAUSE"                 ()
  275.  
  276. DECLARE FUNCTION dwsMUnPause%              ALIAS "DWS_MUNPAUSE"             ()
  277. '******************************************************************************
  278.